<html>
<head>
<style type='text/css'>
body {
   background-color: white;
   margin: 1em 2em 1em 2em;
   font-family: Sans-Serif;
   color: #002;
   line-height: 140%;
   font-size: 12px;
}

h1 {
    font-size: 140%;
}

h2 {
    font-size: 130%;
}

h3 {
    font-size: 120%;
}

h4 {
    font-size: 100%;
    font-style: normal;
    font-weight: bold;
}

h5 {
    font-size: 100%;
    font-style: italic;
    font-weight: normal;
}

pre {
   background-color: #eee;
   padding: 0.5em 0.5em 0.5em 2em;
}

@media print {
   pre {word-wrap:break-word; width:100%;}
} 

ul li,
ol li {
   padding-left: 0.3em;
   /*text-indent: -2em;*/
   margin-bottom: 0.5em;
}

em {
   font-style: normal;
   font-weight: bold;
   text-decoration: underline;
   color: #c40;
}

code {
   font-family: Monospace;
   font-size: 100%;
   color: #c40;
}

a, a * {
   text-decoration: underline;
   color: #14a0d1;
   /* border: 0.5px solid #aaa;
   white-space: nowrap;
   padding-right: 0.1em;
   padding-left: 0.1em;
   padding-bottom: -5px; */
}

a code {
   color: #14a0d1;
}

img {
   position: relative;
   bottom: -4px;
}

div.headline {
   font-weight: bold;
   font-size: 110%;
}

div.copyright {
   margin-top: 1em;
   border-top: 1px solid black;
   padding-top: 0.5em;
}

div.iris_headline {
   border-bottom: 1px solid black;
   padding-bottom: 0.3em;
}

.LaTeX {
   font-family: Monospace;
   font-size: 100%;
   border: 1px solid #060;
   color: #060;
}

code.LaTeX {
   background-color: white;
   padding: 0.5em 0.5em 0.5em 2em;
}
</style>
</head>

<body>
<div class="iris_headline">IRIS Toolbox Reference Manual</div>




<h2 id="model/estimate">estimate</h2>
<div class="headline">Estimate model parameters by optimising selected objective function</div>

<h4 id="syntax">Syntax</h4>
<p>Input arguments marked with a <code>~</code> (tilde) sign may be omitted.</p>
<pre><code>[PEst,Pos,Cov,Hess,M,V,Delta,PDelta] = estimate(M,D,Range,Est,~Spr,...)</code></pre>
<h4 id="input-arguments">Input arguments</h4>
<ul>
<li><p><code>M</code> [ model ] - Model object with single parameterization.</p></li>
<li><p><code>D</code> [ struct | cell ] - Input database or datapack from which the measurement variables will be taken.</p></li>
<li><p><code>Range</code> [ struct | char ] - Date range on which the data likelihood will be evaluated.</p></li>
<li><p><code>Est</code> [ struct ] - Database with the list of paremeters that will be estimated, and the parameter prior specifications (see below).</p></li>
<li><p><code>~SPr</code> [ systempriors | <em>empty</em> ] - System priors object, <a href="../systempriors/Contents.html"><code>systempriors</code></a>; may be omitted.</p></li>
</ul>
<h4 id="output-arguments">Output arguments</h4>
<ul>
<li><p><code>PEst</code> [ struct ] - Database with point estimates of requested parameters.</p></li>
<li><p><code>Pos</code> [ poster ] - Posterior, <a href="../poster/Contents.html"><code>poster</code></a>, object; this object also gives you access to the value of the objective function at optimum or at any point in the parameter space, see the <a href="../poster/eval.html"><code>poster/eval</code></a> function.</p></li>
<li><p><code>Cov</code> [ numeric ] - Approximate covariance matrix for the estimates of parameters with slack bounds based on the asymptotic Fisher information matrix (not on the Hessian returned from the optimization routine).</p></li>
<li><p><code>Hess</code> [ cell ] - <code>Hess{1}</code> is the total hessian of the objective function; <code>Hess{2}</code> is the contributions of the priors to the hessian.</p></li>
<li><p><code>M</code> [ model ] - Model object solved with the estimated parameters (including out-of-likelihood parameters and common variance factor).</p></li>
</ul>
<p>The remaining three output arguments, <code>V</code>, <code>Delta</code>, <code>PDelta</code>, are the same as the <a href="../model/loglik.html"><code>model/loglik</code></a> output arguments of the same names.</p>
<h4 id="options">Options</h4>
<ul>
<li><p><code>'chkSstate='</code> [ <code>true</code> | <em><code>false</code></em> | cell ] - Check steady state in each iteration; works only in non-linear models.</p></li>
<li><p><code>'evalFrfPriors='</code> [ <em><code>true</code></em> | <code>false</code> ] - In each iteration, evaluate frequency response function prior density, and include it to the overall objective function to be optimised.</p></li>
<li><p><code>'evalLik='</code> [ <em><code>true</code></em> | <code>false</code> ] - In each iteration, evaluate likelihood (or another data based criterion), and include it to the overall objective function to be optimised.</p></li>
<li><p><code>'evalPPriors='</code> [ <em><code>true</code></em> | <code>false</code> ] - In each iteration, evaluate parameter prior density, and include it to the overall objective function to be optimised.</p></li>
<li><p><code>'evalSPriors='</code> [ <em><code>true</code></em> | <code>false</code> ] - In each iteration, evaluate system prior density, and include it to the overall objective function to be optimised.</p></li>
<li><p><code>'filter='</code> [ cell | <em>empty</em> ] - Cell array of options that will be passed on to the Kalman filter including the type of objective function; see help on <a href="../model/filter.html"><code>model/filter</code></a> for the options available.</p></li>
<li><p><code>'initVal='</code> [ <code>model</code> | <em><code>struct</code></em> | struct ] - If <code>struct</code> use the values in the input struct <code>Est</code> to start the iteration; if <code>model</code> use the currently assigned parameter values in the input model, <code>M</code>.</p></li>
<li><p><code>'maxIter='</code> [ numeric | <em><code>500</code></em> ] - Maximum number of iterations allowed.</p></li>
<li><p><code>'maxFunEvals='</code> [ numeric | <em><code>2000</code></em> ] - Maximum number of objective function calls allowed.</p></li>
<li><p><code>'noSolution='</code> [ <em><code>'error'</code></em> | <code>'penalty'</code> | numeric ] - Specifies what happens if solution or steady state fails to solve in an iteration: <code>'error='</code> stops the execution with an error message, <code>'penalty='</code> returns an extreme value, <code>1e10</code>, back into the minimization routine; or a user-supplied penalty can be specified as a numeric scalar greater than <code>1e10</code>.</p></li>
<li><p><code>'optimSet='</code> [ cell | <em>empty</em> ] - Cell array used to create the Optimization Toolbox options structure; works only with the option <code>'optimiser='</code> <code>'default'</code>.</p></li>
<li><p><code>'solve='</code> [ <em><code>true</code></em> | <code>false</code> | cellstr ] - Re-compute solution in each iteration; you can specify a cell array with options for the <code>solve</code> function.</p></li>
<li><p><code>'optimiser='</code> [ <em><code>'default'</code></em> | <code>'pso'</code> | cell | function_handle ] - Minimiz ation procedure.</p>
<ul>
<li><p><code>'default'</code>: The Optimization Toolbox function <code>fminunc</code> or <code>fmincon</code> will be called depending on the presence or absence of lower and/or upper bounds.</p></li>
<li><p><code>'alps'</code>: The age layer population structure evolutionary algorithm will be used. See irisoptim.alps help for more information.</p></li>
<li><p><code>'pso'</code>: The particle swarm optimizer will be called. See the irisoptim.pso help for more information.</p></li>
<li><p>function_handle or cell: Enter a function handle to your own optimization procedure, or a cell array with a function handle and additional input arguments (see below).</p></li>
</ul></li>
<li><p><code>'sstate='</code> [ <code>true</code> | <em><code>false</code></em> | cell | function_handle ] - Re-compute steady state in each iteration; you can specify a cell array with options for the <code>sstate</code> function, or a function handle whose behaviour is described below.</p></li>
<li><p><code>'tolFun='</code> [ numeric | <em><code>1e-6</code></em> ] - Termination tolerance on the objective function.</p></li>
<li><p><code>'tolX='</code> [ numeric | <em><code>1e-6</code></em> ] - Termination tolerance on the estimated parameters.</p></li>
</ul>
<h4 id="description">Description</h4>
<p>The parameters that are to be estimated are specified in the input parameter estimation database, <code>E</code> in which you can provide the following specifications for each parameter:</p>
<pre><code>E.parameter_name = { start, lower, upper, logpriorFunc };</code></pre>
<p>where <code>start</code> is the value from which the numerical optimization will start, <code>lower</code> is the lower bound, <code>upper</code> is the upper bound, and <code>logpriorFunc</code> is a function handle expected to return the log of the prior density. You can use the <a href="../logdist/Contents.html"><code>logdist</code></a> package to create function handles for some of the basic prior distributions.</p>
<p>You can use <code>NaN</code> for <code>start</code> if you wish to use the value currently assigned in the model object. You can use <code>-Inf</code> and <code>Inf</code> for the bounds, or leave the bounds empty or not specify them at all. You can leave the prior distribution empty or not specify it at all.</p>
<h5 id="estimating-nonlinear-models">Estimating nonlinear models</h5>
<p>By default, only the first-order solution, but not the steady state is updated (recomputed) in each iteration before the likelihood is evaluated. This behavior is controled by two options, <code>'solve='</code> (<code>true</code> by default) and <code>'sstate='</code> (<code>false</code> by default). If some of the estimated parameters do affect the steady state of the model, the option '<code>sstate='</code> needs to be set to <code>true</code> or to a cell array with steady-state options, as in the function <a href="../model/sstate.html"><code>sstate</code></a>, otherwise the results will be groslly inaccurate or a valid first-order solution will be impossible to find.</p>
<p>When steady state is recomputed in each iteration, you may also want to use the option <code>'chksstate='</code> to require that a steady-state check for all model equations be performed.</p>
<h5 id="user-supplied-optimization-minimization-routine">User-supplied optimization (minimization) routine</h5>
<p>You can supply a function handle to your own minimization routine through the option <code>'optimiser='</code>. This routine will be used instead of the Optim Tbx's <code>fminunc</code> or <code>fmincon</code> functions. The user-supplied function is expected to take at least five input arguments and return three output arguments:</p>
<pre><code>[PEst,ObjEst,Hess] = yourminfunc(F,P0,PLow,PHigh,OptimSet)</code></pre>
<p>with the following input arguments:</p>
<ul>
<li><code>F</code> is a function handle to the function minimised;</li>
<li><code>P0</code> is a 1-by-N vector of initial parameter values;</li>
<li><code>PLow</code> is a 1-by-N vector of lower bounds (with <code>-Inf</code> indicating no lower bound);</li>
<li><code>PHigh</code> is a 1-by-N vector of upper bounds (with <code>Inf</code> indicating no upper bounds);</li>
<li><code>OptimSet</code> is a cell array with name-value pairs entered by the user through the option <code>'optimSet='</code>. This option can be used to modify various settings related to the optimization routine, such as tolerance, number of iterations, etc. Of course, you may simply ignore it and leave this input argument unused;</li>
</ul>
<p>and the following output arguments:</p>
<ul>
<li><code>PEst</code> is a 1-by-N vector of estimated parameters;</li>
<li><code>ObjEst</code> is the value of the objective function at optimum;</li>
<li><code>Hess</code> is a N-by-N approximate Hessian matrix at optimum.</li>
</ul>
<p>If you need to use extra input arguments in your minimization function, enter a cell array instead of a plain function handle:</p>
<pre><code>{@yourminfunc,Arg1,Arg2,...}</code></pre>
<p>In that case, the optimiser will be called the following way:</p>
<pre><code>[PEst,ObjEst,Hess] = yourminfunc(F,P0,PLow,PHigh,Opt,Arg1,Arg2,...)</code></pre>
<h5 id="user-supplied-steady-state-solver">User-supplied steady-state solver</h5>
<p>You can supply a function handle to your own steady-state solver (i.e. a function that finds the steady state for given parameters) through the <code>'sstate='</code> option.</p>
<p>The function is expected to take one input argument, the model object with newly assigned parameters, and return at least two output arguments, the model object with a new steady state (or balanced-growth path) and a success flag. The flag is <code>true</code> if the steady state has been successfully computed, and <code>false</code> if not:</p>
<pre><code>[M,Success] = mysstatesolver(M)</code></pre>
<p>It is your responsibility to add the growth characteristics if some of the model variables drift over time. In other words, you need to take care of the imaginary parts of the steady state values in the model object returned by the solver.</p>
<p>Alternatively, you can also run the steady-state solver with extra input arguments (with the model object still being the first input argument). In that case, you need to set the option <code>'sstate='</code> to a cell array with the function handle in the first cell, and the other input arguments afterwards, e.g.</p>
<pre><code>&#39;sstate=&#39;,{@mysstatesolver,1,&#39;a&#39;,X}</code></pre>
<p>The actual function call will have the following form:</p>
<pre><code>[M,Success] = mysstatesolver(M,1,&#39;a&#39;,X)</code></pre>
<h4 id="example">Example</h4>

</body>
<div class="copyright">IRIS Toolbox. Copyright &copy; 2007-2015 IRIS Solutions Team.</div>
</html>
